Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EOSQLExpression

Inherits From:	NSObject

Conforms To:	NSCopying
EOExpressionContext

Declared In:	eoaccess/EOSQLExpression.h

Class Description

Adaptors use instances of EOSQLExpression to perform their four basic operations: select, insert, update, and delete. EOSQLExpression is an abstract superclass, which you can subclass for your own adaptor if you need to. EOSQLExpression objects are used internally by the Framework and by an adaptor; your application should never need to create or use one itself.

EOSQLExpression's default implementations of its expression-building methods obtain the adaptor's query language expression subclass and use it to build an expression object describing the desired operation. This expression object can then be turned into a string with an expressionValueForContext: message (with itself as the context) and be passed to evaluateExpression: for interpretation by the database server.

Building Expressions

These four class methods build SQL statements:

deleteExpressionWithQualifier:channel:
insertExpressionForRow:entity:channel:
selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:
updateExpressionForRow:qualifier:channel:

An individual SQL statement is constructed from the expression values of any modeling or value objects specified in the ªbuildº method and combining them in the appropriate form. An object's expression value is a string representation that the database understands; for example, an EOAttribute's expression value is ultimately its column name. See the EOExpression informal protocol specification for more information. The EOSQLExpression usually asks its adaptor to get the expression values for attributes and values with the formatAttribute: and formatValue:forAttribute: messages; for other kinds of objects (such as EORelationships and EOExpressionArrays) it simply sends expressionValueForContext:.

Each of the ªbuildº methods mentioned above invokes a number of instance methods. These methods are documented individually below.

Instance Variables

None declared in this class.

Adopted Protocols

NSCopying	- copy
- copyWithZone:

EOExpressionContext:	- expressionValueForAttribute:
- expressionValueForAttributePath:

Method Types

Building SQL expressions	+ deleteExpressionWithQualifier:channel:
+ insertExpressionForRow:entity:channel:
+ selectExpressionForAttributes:lock:qualifier:
fetchOrder:channel:
+ updateExpressionForRow:qualifier:channel:

Creating components	- columnListForRow:entity:
- fromClauseForRelationshipPaths:entity:
- joinExpressionForOperator:semantic:
source:destination:
- joinExpressionForRelationshipPaths:entity:
- lockClause
- orderByClauseForFetchOrder:
- selectListWithAttributes:
- updateListForRow:entity:
- valueListForRow:entity:
- whereClauseForQualifier:joinExpresssion:

Final initialization	- finishBuildingExpression

Caching aliases	- relationshipPathsForAttributes:qualifier:fetchOrder:

Getting the entity	- entity

Class Methods

deleteExpressionWithQualifier:channel:

+ deleteExpressionWithQualifier:(EOQualifier *)aQualifier channel:(EOAdaptorChannel *)aChannel

Creates and returns a SQL DELETE statement to delete the rows described by aQualifier. Invokes whereClauseForQualifier: to create the WHERE clause and finishBuildingExpression to finalize the statement.

insertExpressionForRow:entity:channel:

+ insertExpressionForRow:(NSDictionary *)aRow
entity:(EOEntity *)anEntity
channel:(EOAdaptorChannel *)aChannel

Creates and returns a SQL INSERT statement to insert the values in row as a new row in the table corresponding to anEntity. Invokes columnListForRow: and valueListForRow: to create the INSERT statement and finishBuildingExpression to finalize the statement.

selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:

+ selectExpressionForAttributes:(NSArray *)attributes
lock:(BOOL)flag
qualifier:(EOQualifier *)aQualifier
fetchOrder:(NSArray *)fetchOrder
channel:(EOAdaptorChannel *)aChannel

Creates and returns a SQL SELECT statement to select attributes according to aQualifier, locking according to flag and ordering by fetchOrder. Invokes selectListWithAttributes:, fromClauseForRelationshipPaths:entity:, orderByClauseForFetchOrder:, joinExpressionForRelationshipPaths:entity: and whereClauseForQualifier:joinExpression: to create the SELECT statement and finishBuildingExpression to finalize the statement. If flag is YES, invokes lockClause.

An EOSQLExpression caches different references to tables under the relationship paths used to access them, and performs aliasing when generating the expression. These aliases are computed by relationshipPathsForAttributes:qualifier:fetchOrder:.

updateExpressionForRow:qualifier:channel:

+ updateExpressionForRow:(NSDictionary *)newValues
qualifier:(EOQualifier *)aQualifier
channel:(EOAdaptorChannel *)aChannel

Creates and returns a SQL UPDATE statement to set newValues for the row described by aQualifier, each of which contains only the information needed to update values that are changing. Invokes updateListForRow:entity:, whereClauseForQualifier:joinExpression: to create the UPDATE statement and finishBuildingExpression to finalize the statement.

Instance Methods

columnListForRow:entity:

- columnListForRow:(NSDictionary *)aRow entity:(EOEntity *)anEntity

Builds and returns an expression object containing a list of column names from aRow, suitable for use in a SQL insert statement. For example, with a row containing values for attributes with the external names ªemp_idº, ªlast_nameº, and ªfirst_nameº this method returns an object whose expression value is ª(emp_id, last_name, first_name)º.

entity

- (EOEntity *)entity

Returns the entity of the qualifier the EOSQLExpression was created with.

finishBuildingExpression

- finishBuildingExpression

This method is invoked on each EOSQLExpression object created by any of the four principal statement-building methods just before it is returned to the caller. This gives subclasses one last chance to make final modifications to the statement after it has been completely assembled. Returns self.

fromClauseForRelationshipPaths:entity:

- fromClauseForRelationshipPaths:(NSDictionary *)relationshipPaths entity:(EOEntity *)anEntity

Builds and returns an expression object representing a SQL FROM clause using a dictionary of aliased relation paths. The aliases for the relationship paths are built from the attributes, qualifier, and fetch order specified to selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:, which invokes this method.

joinExpressionForOperator:semantic:source:destination:

- joinExpressionForOperator:(EOJoinOperator)operator
semantic:(EOJoinSemantic)semantic
source:sourceExpression
destination:destinationExpression

Builds and returns an expression object joining sourceExpression and destinationExpression, and which specifies the join operator and join semantic. For example, with the following argument values:

Argument	Value

operator	EOJoinEqualTo
semantic	EOLeftOuterJoin
sourceExpression	ªt0.empIDº
destinationExpression	ªt1.empIDº

this method returns an object whose expression value is ªt0.empID * = t1.empIDº.

You may need to override this method for a particular database server.

joinExpressionForRelationshipPaths:entity:

- joinExpressionForRelationshipPaths:(NSDictionary *)relationshipPaths entity:(EOEntity *)entity

Builds and returns an expression object specifying all the joins of the relationships in relationshipPaths for a SELECT statement.

See also:  + selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:

lockClause

- lockClause

Returns a string that can be inserted into a SELECT statement to cause the server to lock any records fetched by the SELECT statement. You usually have to override this method for a particular database server.

See also:  + selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:

orderByClauseForFetchOrder:

- orderByClauseForFetchOrder:(NSArray *)fetchOrder

Builds and returns an expression object representing a SQL ORDER-BY clause for fetchOrder. This clause is used in building a SELECT statement.

For example, with a fetch order as defined in the following table:

Attribute Column Name	Ordering

salary	EODescendingOrder
last_name	EOAscendingOrder
first_name	EOAscendingOrder

this method returns an object whose expression value is ª ORDER BY salary DESC, last_name, first_nameº.

See also:  + selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:

relationshipPathsForAttributes:qualifier:fetchOrder:

- (NSMutableDictionary *)relationshipPathsForAttributes:(NSArray *)attributes
qualifier:(EOQualifier *)aQualifier
fetchOrder:(NSArray *)fetchOrder

Computes aliases for all relationships referred to within attributes, aQualifier, and fetchOrder. Returns a dictionary whose keys are the data paths aliased and whose values are the aliases for those data paths. These aliases are used for constructing the select list and the join expressions in a SELECT statement.

See also:  + selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:

selectListWithAttributes:

- selectListWithAttributes:(NSArray *)attributes

Builds and returns an expression object containing a list of aliased attribute names, suitable for use in a SQL SELECT list.

See also:  + selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:

updateListForRow:entity:

- updateListForRow:(NSDictionary *)row entity:(EOEntity *)entity

Builds and returns an expression object containing a list of column assignment clauses suitable for use in a SQL UPDATE statement.

See also:  + updateExpressionForRow:qualifier:channel:

valueListForRow:entity:

- valueListForRow:(NSDictionary *)aRow entity:(EOEntity *)anEntity

Builds and returns an expression object containing a list of values suitable for use in a SQL INSERT statement.

See also:  + insertExpressionForRow:entity:channel:

whereClauseForQualifier:joinExpresssion:

- whereClauseForQualifier:(EOQualifier *)aQualifier joinExpresssion:joinExpression

Builds and returns an expression object containing a SQL WHERE clause using aQualifier and joinExpression. joinExpression is an NSString or EOExpressionArray created with joinExpressionForOperator:semantic:source:destination:.

See also:  + insertExpressionForRow:entity:channel:, + selectExpressionForAttributes:lock:qualifier:fetchOrder:channel:, + updateExpressionForRow:qualifier:channel: